JavaScript SDK 使用指南

本指南将会为您介绍如何使用JavaScript SDK接入您的项目，建议在接入开始前，先阅读数据规则一章，在了解TA数据规则后再进行接入。如果您想要了解游戏行业应该收集哪些数据以及如何收集，请查阅接入样例。您可以在访问GitHub获取JavaScript SDK的源代码。

最新版本为：1.2.0

更新时间为：2019-10-22

下载地址

1. 引入JavaScript SDK

1.下载JavaScript SDK

2.载入JavaScript SDK

请将以下代码置入html的<head>，或其他初始化代码中，并配置对应参数：

<!--Thinking Analytics SDK BEGIN-->
<script>
    !function (e) { if (!window.ThinkingDataAnalyticalTool) { var n = e.sdkUrl, t = e.name, r = window, a = document, i = "script", l = null, s = null; r.ThinkingDataAnalyticalTool = t; var o = ["track", "quick", "login", "identify", "logout", "trackLink", "userSet", "userSetOnce", "userAdd", "userDel", "setPageProperty", "setSuperProperties", "setDynamicSuperProperties", "clearSuperProperties", "timeEvent", "unsetSuperProperties", "initInstance"]; r[t] = function (e) { return function () { if (this.name) (r[t]._q = r[t]._q || []).push([e, arguments, this.name]); else if ("initInstance" === e) { var n = arguments[0]; r[t][n] = { name: n }; for (var a = 0; a < o.length; a++)r[t][n][o[a]] = r[t].call(r[t][n], o[a]); (r[t]._q1 = r[t]._q1 || []).push([e, arguments]) } else (r[t]._q = r[t]._q || []).push([e, arguments]) } }; for (var u = 0; u < o.length; u++)r[t][o[u]] = r[t].call(null, o[u]); r[t].param = e, r[t].__SV = 1.1, l = a.createElement(i), s = a.getElementsByTagName(i)[0], l.async = 1, l.src = n, s.parentNode.insertBefore(l, s) } }(
    {
        appId:'APP_ID', //系统分配的APPID
        name: 'ta', //全局的调用变量名，可以任意设置，后续的调用使用该名称即可
        sdkUrl:'./thinkingdata.js', //统计脚本URL
        serverUrl:'http://receiver.ta.thinkingdata.cn:9080/sync_js', //数据上传的URL
        send_method:'image', //数据上传方式
        useAppTrack: true, // 打通 APP 与 H5
        showLog: true, //是否打印上报数据  
        loaded: function(ta) {
           // var currentId = ta.getDistinctId();
           // ta.identify(currentId);
           // ta.quick('autoTrack');
        }
    });
</script>
<!--Thinking Analytics SDK END-->

appId是您的项目的APP_ID，需要进行配置，在您申请项目时会给出，请在此处填入
name为全局的调用变量名
sdkUrl为sdk的URL，需要进行配置
serverUrl为上传数据的URL，需要进行配置

如果您使用的是云服务，请输入以下URL: https://receiver.ta.thinkingdata.cn/sync_js 或http://receiver.ta.thinkingdata.cn/sync_js 如果您使用的是私有化部署的版本，请输入以下URL: http://数据采集地址/sync_js

send_method为数据上报方式，默认为'image'，即使用图片GET请求方式上报数据，可以替换为'ajax'
useAppTrack为是否开启与APP的打通，在需要采集APP中的H5页面数据是设置，true为开启，默认为false，即不开启；详情可查看H5 与 APP SDK 打通一节。
showLog 为是否打印上报数据，打开后将会在浏览器控制台打印上报的数据，默认为true即开启
loaded，初始化回调函数，使用代码片段载入为异步载入，因此有返回值的方法可能调用不成功，或者在SDK加载完成前触发的track将会出现异常。我们在参数中提供了loaded 属性，loaded 中的回调函数将会在初始化完成后、开始上报数据前被调用，比如在此设置用户ID，则SDK载入前产生的数据，将会被设置上述用户ID。

2. 设置用户ID

在JS SDK载入完成之后，SDK将会自动生成一个UUID作为每个用户的默认访客ID，该ID将会作为用户在未登录状态下的身份识别。如果您的用户存在账号ID，请使用login设置用户的账号ID。

a) 设置访客ID（可选）

如果用户在您的产品中可以未登录状态下使用，且您需要配置用户在未登录状态下的访客ID，则您可以调用identify来进行设置：

ta.identify('123ABCabc');

如果需要获得访客ID，可以调用getDistinctId获取：

//返回访客ID，多实例的情况下，返回的是调用实例的访客ID
var distinctId = ta.getDistinctId();

b) 设置账号ID

在用户产生登录行为时，可调用login来设置用户的账号ID。TA平台优先以账号ID作为身份标识，设置后的账号ID将会被保存，多次调用login将会覆盖先前的账号ID：

//用户的登录唯一标识，此数据对应上报数据里的#account_id，此时"#account_id"的值为"ABC_123456"
ta.login('ABC_123456'); 
//再次调用login调整账号ID，此时"#account_id"的值为"XYZ_987654"
ta.login('XYZ_987654');

请注意，该方法不会上传用户登录的事件

c) 清除账号ID

在用户产生登出行为之后，可调用logout来清除账号ID，在下次调用login之前，将会以访客ID作为身份识别ID：

//去除上报数据里的#account_id，之后的数据将不带有"#account_id"
ta.logout();

请注意，该方法不会上传用户登出的事件

3. 发送事件

a) 上传事件

您可以直接调用track上传自定义事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：

ta.track(
   'Purchase',              //追踪事件的名称
    {
        'Item':'商品A',
        'ItemNum':1,
        'Cost':100
    }                       //需要上传的事件属性
);

track接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性
事件的名称是字符串，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
事件的属性是一个JSON对象，其中元素必须是key : value的形式，每个元素代表一个属性。
Key的值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
Value为该属性的值，支持支持String、Number、Boolean和Date。

b）监控HTML元素点击事件

如果您想要追踪页面上元素的点击事件，可以使用trackLink对HTML元素进行批量监控：

ta.trackLink(
    {
        'tag':['a','button'],             //HTML标签
        'class':['class1','class2'],      //自定义的Class名称
        'id':['id1','id2']                //自定义的ID名称
         },                               //监控元素的规则
    'click',                              //追踪事件的名称
    {                    
        'production':'产品名',
        'name':'元素标识名'
        }                                 //事件的属性        
);

第一个参数是您需要监控的元素的规则，类型是JSON对象，支持根据HTML标签类型、Class以及id追踪需要监控的页面元素，至少要选择一种途经选取DOM元素。对于满足规则的元素，会通过事件监听器的方式监控元素的点击事件，当监听元素被点击时，将会上报一个事件，事件名和事件属性取后续两个参数的值
第二个参数是事件的名称，为string类型，规则与track接口的事件名一致，必须填写
第三个参数是事件的属性，类型是JSON对象，如果没有需要上报的属性，可传入空JSON
本接口规定事件属性'name'为元素的标识，如果参数三中没有设置事件属性'name'，则本接口将会根据以下逻辑，获取被监控元素的特定属性值作为元素标识。取值，元素的自定义属性'td-name'，元素的innerHTML，元素的value，如果都没有取到则传'未获取标识'

本接口只会在被调用时为符合规则的元素设置事件监听器，因此在调用接口后元素的标识发生变化，或者新生成了符合规则的元素，监听器上报的事件不会做出相应的改变，如果需要监控新生成元素，可在ajax中元素被生成后调用本接口。

c) 设置公共事件属性

在采集数据的过程中，有一些字段会被多个事件所共用，比如发生在同一页面上的所有事件，都应该带有这个页面的页面属性，用户的账号信息应该在所有数据中都带有。那么在调用track上报事件时，这些属性每次都需要设置一遍，针对这样的属性，可以使用公共属性设置接口来统一设置：

1. 公共属性类型

在介绍如何设置公共属性之前，您需要先了解三种类型的公共属性的特性，根据实际需求，选用适合的类型：

页面公共属性: 针对当前页面生效，优先级最高。如果重新初始化 SDK，页面公共属性会被清空。只能设置定值。
动态公共属性: 针对当前页面生效，优先级次于页面公共属性。重新初始化SDK后，需要再次设置动态公共属性，可以设置动态变量。
静态公共属性: 对所有页面生效. 优先级最低，开启缓存的情况下，会缓存在 localStorage 或 cookie 中。只能设置定值。

2. 设置页面公共属性

对于一些页面中的静态属性，比如一个页面的名称或者地址，您可能希望在这个页面中触发的所有事件上都加入这个属性。类似这样的、需要适用于页面中所有事件的静态属性，您可以使用setPageProperty进行设置，请注意，使用setPageProperty设置的公共属性只对当前页面有效

//将页面ID设置为页面公共属性，该页面中触发的所有事件，都会带有以下属性 
ta.setPageProperty({'page_id': 'page10001'});

如果您希望获取当前页面的页面公共属性，可以调用getPageProperty来获取

//获取当前页面的页面公共属性
var pageProperty = ta.getPageProperty();

3. 设置页面动态公共属性

在1.1.0版本中，新增了页面动态公共属性的特性。通过setDynamicSuperProperties设置动态公共属性的回调函数，SDK 将会在事件上报时触发回调函数，并把返回JSON对象加入到事件属性中。

setDynamicSuperProperties的参数是一个函数，函数需要返回一个JSONObject对象，其中每个元素代表一个属性。
Key的值为属性的名称，为String类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
Value为该属性的值，支持String、Number、Boolean和Date。

// 设置动态公共属性，在事件上报时触发回调函数，并把返回的JSON对象加入到事件属性中

ta.setDynamicSuperProperties(
    function() {
        var d = new Date();
        d.setHours(10);
        return {'date': d}
    });

/*  
ta.setDynamicSuperProperties(
    ()=>{
        var d = new Date();
        d.setHours(10); 
        return {'date': d}
    });
*/

4. 设置静态公共属性

对于一些重要的属性，譬如用户的渠道、昵称、ID等，这些属性需要设置在每个事件中，您可以调用setSuperProperties来设置静态公共事件属性，静态公共事件属性会对全局生效。当开启缓存时（默认打开），静态公共属性会缓存在 localStorage 或 cookie 中。

公共事件属性同样也是一个JSONObject对象，其中每个元素代表一个属性。
Key的值为属性的名称，为String类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
Value为该属性的值，支持String、Number、Boolean和Date。

//设置公共事件属性，所有数据事件中都会带有这些属性

ta.setSuperProperties({'channel':'渠道名','user_name':'用户名'});

如果您需要所有获取已设置静态公共属性，可以调用getSuperProperties；如果您需要删除某个静态公共属性，您可以调用unsetSuperProperty清除其中一个静态公共属性；如果您想要清空所有静态公共属性，则可以调用clearSuperProperties。

//获取静态公共事件属性
    var superProperties = ta.getSuperProperties();

//清除一条静态公共事件属性，比如将之前设置'channel'属性清除，之后的数据将不会该属性
    ta.unsetSuperProperty('channel');

//清除所有静态公共事件属性
    ta.clearSuperProperties();

d) 记录事件时长

您可以调用timeEvent来开始计时，配置您想要计时的事件名称，当您上传该事件时，计时将会结束，并且SDK将会自动在该事件的事件属性中加入#duration属性来表示记录的时长，单位为秒，timeEvent支持跨页面计时。

//开始计时，记录的事件为'Purchase'
    ta.timeEvent('Purchase');

//其他代码

//上传事件，计时结束，'Purchase'这一事件中将会带有表示事件时长的属性"#duration"   
    ta.track('Purchase', {'Item':'商品A','ItemNum':1,'Cost':100});

e) 自动采集页面浏览事件

TA提供自动采集页面浏览事件的接口，您只需使用以下代码，JS SDK将会自动上传用户浏览页面的事件：

ta.quick('autoTrack');

4. 用户属性

a) 设置用户属性（`userSet`）

对于一般的用户属性，您可以调用userSet来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性

//设置用户属性，设置会员等级
ta.userSet({'vip_level':'钻石会员'});

b) 初始化用户属性（`userSetOnce`）

如果您要上传的用户属性只要设置一次，则可以调用userSetOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。

//以设置用户名为例，如果用户名已设置，则忽略本次设置，如果不存在，则设置为传入值
ta.userSetOnce({'UserName':'TA'});

c) 累加用户属性（`userAdd`）

当您要上传数值型的属性时，您可以调用userAdd来对该属性进行累加操作，如果该属性还未被设置，则会赋值0后再进行计算

//以付费为例，用户每次付费时调用此接口，则'total_revenue'字段每次会做累加付费金额的处理
ta.userAdd({'total_revenue':50});

d) 重置用户属性（`userUnset`）

当您要清空用户的某个用户属性值时，您可以调用userUnset来对指定属性进行清空操作，如果该属性还未在集群中被创建，则userUnset不会创建该属性

//清空该用户属性名为userPropertykey的用户属性值，即设置成NULL
ta.userUnset('userPropertykey');

e) 删除用户（`userDel`）

如果您要删除某个用户，可以调用userDel将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

ta.userDel();

5. 进阶功能

a) 多实例

在1.1.0版本，加入了多实例的功能，可以通过调用 initInstance 方法，可以创建子实例对象。其参数为子实例名称。之后您可以通过该名称调用子实例的接口.

// 创建一个名字为 newInstance 的实例
ta.initInstance('newInstance');

// 为子实例设置 distinct_id 并发送 test_event 的事件
ta.newInstance.identify('new_distinct_id');
ta.newInstance.track('test_event');

默认情况下，子实例与主实例采用相同的配置（appId, serverUrl等）。并且默认情况下，子实例不会开启本地缓存。

如果需要为子实例单独配置参数，可以在初始化时传入配置信息，通过在配置信息中传入不同的appId值，可以达到向不同项目上报数据的功能:

var param = {
  appId: 'debug-appid',
  serverUrl: 'ANOTHER_SERVER_URL',
  persistenceEnabled: true, // 开启子实例的本地缓存，子实例本地缓存根据子实例名称 name 区分
  send_method:'image',
  showLog: true 
}

ta.initInstance('anotherInstance', param);

//往主实例项目中上报数据
ta.track('Event');

//往子实例项目中上报数据
ta.anotherInstance.track('Event');

主实例与子实例的ID体系不互通，公共属性不互通，可以单独为每个实例设置用户ID，以下案例通过这一特性，为邀请好友这一事件的邀请者和被邀请者，分别上报了邀请成功和被邀请事件

//主实例是被邀请的新用户，子实例是邀请者
ta.login('invitee');
ta.anotherInstance.login('inviter');

//新用户触发被邀请事件
ta.track('be_invited');

//邀请者触发邀请新用户事件
ta.anotherInstance.track('invite_new_user');

b) 获取设备ID

在1.1.0版本，加入了获取设备ID（也就是预置属性#device_id）的接口，您可以通过调用getDeviceId来获取设备ID：

var deviceId = ta.getDeviceId();

//如果需要将设备ID设置成访客ID可以如下调用
//ta.identify(ta.getDeviceId());

6. 相关预置属性

6.1 所有事件带有的预置属性

以下预置属性，是JavaScript SDK中所有事件（包括自动采集事件）都会带有的预置属性

属性名	中文名	说明
#ip	IP地址	用户的IP地址，TA将以此获取用户的地理位置信息
#country	国家	用户所在国家，根据IP地址生成
#country_code	国家代码	用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据IP地址生成
#province	省份	用户所在省份，根据IP地址生成
#city	城市	用户所在城市，根据IP地址生成
#device_id	设备ID	用户的设备ID
#screen_height	屏幕高度	用户设备的屏幕高度，如1920等
#screen_width	屏幕宽度	用户设备的屏幕高度，如1080等
#lib	SDK类型	您接入SDK的类型，如JavaScript等
#lib_version	SDK版本	您接入SDK的版本
#browser	浏览器类型	用户使用的浏览器类型，如Chrome，Firefox等
#browser_version	浏览器版本	用户使用的浏览器的版本，如Chrome 61.0，Firefox 57.0等
#url	页面地址	当前页面的地址
#url_path	页面路径	当前页面的路径
#referrer	前向地址	跳转前页面的地址
#referrer_host	前向路径	跳转前页面的路径
#title	页面标题	当前页面的标题
#zone_offset	时区偏移	数据时间相对UTC时间的偏移小时数

ChangeLog

1.2.0 2019/10/22

新增user_unset接口，可用于清空一个用户属性
新增预制属性#zone_offset，单位为小时。默认情况下会将本地时区的偏移上报到服务端，该时间偏移会受夏令时影响。满足如下公式：
```
utc_time + #zone_offset = #event_time
```

1.1.0 2019/07/23

默认使用 localStorage 缓存 #device id, #distinct id, #account id 等需要持久化的数据
支持多实例: 多个实例之间原则上只有 #device id 是共享的. 其他的所有属性和配置都不共享，可以分别向不同的项目中上报各自的数据
增加接口：
- getDeviceId()
- getDistinctId()
- getPageProperty()
- setSuperProperties(superProperties)
- unsetSuperProperty(propertyName)
- clearSuperProperties()
- getSuperProperties()
- setDynamicSuperProperties(function)
- timeEvent(eventName)
增加属性合法性校验逻辑
自动采集点击事件优化:
- 增加 #element_type 属性, 传入 nodeName
- 增加页面属性，类似于ta_pageview
- 优化自动采集逻辑，修复已知BUG
初始化参数中增加 loaded 参数, 可以传入回调函数。当初始化完成时，会回调此函数.
其他优化：
- 修复 device id 未持久化bug
- 优化初始化逻辑
- 预置属性增加 #os 采集ua 中的操作系统信息

1.0.7 2019/05/31

修复兼容性Bug

1.0.6 2019/05/10

支持 identify 接口

JavaScript SDK 使用指南

JavaScript SDK 使用指南

1. 引入JavaScript SDK

2. 设置用户ID

a) 设置访客ID（可选）

b) 设置账号ID

c) 清除账号ID

3. 发送事件

a) 上传事件

b）监控HTML元素点击事件

c) 设置公共事件属性

1. 公共属性类型

2. 设置页面公共属性

3. 设置页面动态公共属性

4. 设置静态公共属性

d) 记录事件时长

e) 自动采集页面浏览事件

4. 用户属性

a) 设置用户属性（`userSet`）

b) 初始化用户属性（`userSetOnce`）

c) 累加用户属性（`userAdd`）

d) 重置用户属性（`userUnset`）

e) 删除用户（`userDel`）

5. 进阶功能

a) 多实例

b) 获取设备ID

6. 相关预置属性

6.1 所有事件带有的预置属性

ChangeLog

1.2.0 2019/10/22

1.1.0 2019/07/23

1.0.7 2019/05/31

1.0.6 2019/05/10

results matching ""

No results matching ""

JavaScript SDK 使用指南

1. 引入JavaScript SDK

2. 设置用户ID

a) 设置访客ID（可选）

b) 设置账号ID

c) 清除账号ID

3. 发送事件

a) 上传事件

b）监控HTML元素点击事件

c) 设置公共事件属性

1. 公共属性类型

2. 设置页面公共属性

3. 设置页面动态公共属性

4. 设置静态公共属性

d) 记录事件时长

e) 自动采集页面浏览事件

4. 用户属性

a) 设置用户属性（userSet）

b) 初始化用户属性（userSetOnce）

c) 累加用户属性（userAdd）

d) 重置用户属性（userUnset）

e) 删除用户（userDel）

5. 进阶功能

a) 多实例

b) 获取设备ID

6. 相关预置属性

6.1 所有事件带有的预置属性

ChangeLog

1.2.0 2019/10/22

1.1.0 2019/07/23

1.0.7 2019/05/31

1.0.6 2019/05/10

results matching ""

No results matching ""

a) 设置用户属性（`userSet`）

b) 初始化用户属性（`userSetOnce`）

c) 累加用户属性（`userAdd`）

d) 重置用户属性（`userUnset`）

e) 删除用户（`userDel`）